@wonseok-han/confluence-sync 1.0.0 → 1.1.0

package/README.md

@@ -5,7 +5,9 @@
 - **push** — 로컬 `.md` 디렉토리를 Confluence 페이지 트리로 발행. 폴더 구조가 그대로 페이지 계층이 됩니다.
 - **pull** — Confluence 페이지·폴더·**스페이스 전체**를 읽어 `.md` 로 가져옵니다.
 
-문서를 git으로 관리하면서(docs-as-code) Confluence를 미러로 두거나, 반대로 Confluence에 쌓인 문서를 마크다운으로 내려받아 쓸 수 있습니다. 내려받은 마크다운은 Obsidian·VS Code 등 어디서든 그대로 열립니다.
+문서를 git으로 관리하면서(docs-as-code) Confluence를 미러로 두거나, 반대로 Confluence에 쌓인 문서를 마크다운으로 내려받아 쓸 수 있습니다.
+
+**[Obsidian](#obsidian) vault 와 그대로 맞물립니다** — pull 한 문서는 내부 링크가 이어져 그래프 뷰가 동작하고, vault 에서 쓴 `[[wikilink]]`·`![[embed]]`·frontmatter 를 push 가 그대로 이해합니다.
 
 ---
 
@@ -20,6 +22,8 @@ confluence-sync --help
 
 공개 npm 패키지라 **토큰이나 `.npmrc` 설정이 필요 없습니다.** (Node 20+)
 
+> 짧은 이름 **`csync`** 도 같이 설치됩니다 — 아래 예시의 `confluence-sync` 는 전부 `csync` 로 바꿔 쓸 수 있습니다.
+
 ## 빠른 시작
 
 ```bash
@@ -122,10 +126,11 @@ docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
 
 ### 변환 규칙
 
-- 각 문서의 **첫 `# 제목`** 이 페이지 제목이 되고, 본문은 storage format 으로 변환됩니다.
+- 페이지 제목은 **frontmatter `title` → 첫 `# 제목` → 파일명** 순으로 정해지고, 본문은 storage format 으로 변환됩니다.
 - 코드블록 → **code 매크로**, 표·리스트·헤딩은 그대로.
-- **내부 `.md` 링크** → Confluence 페이지 링크로 자동 변환.
-- **로컬 이미지** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
+- **내부 `.md` 링크**와 **`[[wikilink]]`** → Confluence 페이지 링크로 자동 변환.
+- **로컬 이미지**와 **`![[embed]]`** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
+- **YAML frontmatter** 는 메타데이터로만 쓰이고 본문에 새지 않습니다.
 
 ### 변경 감지와 매핑
 
@@ -162,15 +167,113 @@ confluence-sync pull <pageId|url>                  # 한 페이지를 현재 폴
 confluence-sync pull <url> --out ./docs            # 출력 디렉토리 지정
 confluence-sync pull <url> --out ./docs --children # 하위 페이지·폴더까지 트리로 복원
 confluence-sync pull --space --out ./docs          # 스페이스 전체 (홈페이지부터 전부)
+confluence-sync pull --space --obsidian --out ~/MyVault   # 내부 링크를 [[wikilink]] 로
 ```
 
 - 대상은 **숫자 ID** 또는 **URL** (`.../pages/<ID>/...` 페이지, `.../folder/<ID>` 폴더) 둘 다 됩니다.
 - **`--children`** — 하위를 재귀 복원합니다. 자식이 있는 페이지는 `<제목>/README.md` 폴더로 펼쳐져 **push 계층 관례와 맞물립니다**.
 - **`--space`** — 대상 없이 스페이스 전체를 가져옵니다. 페이지가 많으면 시간이 걸립니다.
 - **이미지/첨부** 는 문서별로 `attachments/<문서명>/` 아래에 내려받고 링크를 그 경로로 씁니다 (문서 폴더가 이미지로 지저분해지지 않음). 다운로드에는 `read:attachment` 스코프가 필요합니다.
+- **내부 링크** 는 같은 실행에서 함께 받은 페이지끼리 **상대 `.md` 링크로 이어집니다.** 받지 않은 페이지는 절대 URL 로 남습니다(깨진 링크를 만들지 않음).
+- 각 문서 머리에 **frontmatter** 가 붙습니다 — `title` · `pageId` · `spaceKey` · `source` · `updated`. `pageId` 가 다시 push 할 때의 앵커입니다.
+- 제목은 frontmatter 의 `title` 로만 들어가고 **본문에 `# 제목` 을 따로 넣지 않습니다** — 제목을 별도로 표시하는 뷰어(Obsidian 등)에서 두 번 보이기 때문입니다. push 는 `title` 을 먼저 읽으므로 왕복에 문제가 없습니다.
 - 본문은 `export_view`(HTML)를 [turndown](https://github.com/mixmark-io/turndown) 으로 변환합니다 — 코드블록(언어 포함, 미지정은 `plaintext`), GFM 표, 리스트 등.
 
-> **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다. 내부 페이지 링크는 절대 URL로 유지됩니다.
+> **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다.
+
+---
+
+## Obsidian
+
+pull 이 만드는 마크다운은 **vault 에 그대로 열립니다.** 별도 플러그인이 필요 없습니다.
+
+```bash
+cd ~/MyVault
+confluence-sync pull --space --out .              # 스페이스 전체를 vault 로
+confluence-sync pull --space --out . --obsidian   # 내부 링크를 [[wikilink]] 로
+```
+
+- 내부 링크가 이어져 있어 **그래프 뷰·백링크가 그대로 동작**합니다. 기본값인 상대 `.md` 링크도 Obsidian 에서 정상 동작하며 GitHub·VS Code 에서도 열립니다. vault 안에서만 쓸 거라면 `--obsidian` 으로 `[[wikilink]]` 를 받으세요.
+- frontmatter 는 Obsidian 속성 패널에 표시되고, `source` 로 원본 페이지를 바로 열 수 있습니다.
+
+---
+
+## `convert` — 이미 받아둔 문서 손보기
+
+**다시 pull 하지 않고** 로컬 `.md` 트리를 제자리에서 고칩니다. Confluence 를 호출하지 않으니 인증도 필요 없습니다.
+
+```bash
+confluence-sync convert --to obsidian ./docs            # 상대 .md 링크 → [[wikilink]]
+confluence-sync convert --to markdown ./docs            # 되돌리기
+confluence-sync convert --fix ./docs                    # 옛 pull 결과 보정
+confluence-sync convert --to obsidian --fix ./docs      # 둘 다
+confluence-sync convert --fix ./docs --dry-run          # 바뀔 파일만 미리보기
+```
+
+### 대상 지정
+
+파일·폴더를 **여러 개** 줄 수 있고, 안 주면 base 전체가 대상입니다.
+
+```bash
+confluence-sync convert --fix ./docs/가이드/설치.md          # 파일 하나만
+confluence-sync convert --fix ./docs/a.md ./docs/나머지/     # 파일 + 폴더 혼합
+```
+
+`--base` 는 **링크를 해석하는 범위**입니다. 파일 하나만 고칠 때도 주변 문서를 알아야 이름이 유일한지, 링크 대상이 실재하는지 판정할 수 있기 때문입니다. 지정하지 않으면 준 경로들의 공통 상위 폴더가 되며, `--to` 로 링크를 바꿀 때는 **문서 트리 루트를 `--base` 로 알려주는 편이 정확합니다.**
+
+```bash
+confluence-sync convert --to obsidian ./docs/가이드/설치.md --base ./docs
+```
+
+### 다른 곳에 내보내기 — `--out`
+
+`--out` 없이 실행하면 **원본을 덮어씁니다.** 원본을 그대로 두고 결과만 따로 받으려면:
+
+```bash
+confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
+```
+
+- base 기준 상대 경로를 그대로 재현하고, **본문이 참조하는 첨부(이미지)도 같이 복사**합니다 — 안 그러면 링크가 깨집니다.
+- 안 바뀐 문서도 함께 내보내 **온전한 트리**가 나옵니다.
+- `--out` 이 base 안이면 원본을 오염시키므로 거부합니다.
+
+### 링크 표기 (`--to`)
+
+두 방향은 서로의 역변환이라 **왕복해도 내용이 보존됩니다.** 안전하게 바꿀 수 있는 링크만 건드립니다.
+
+- 외부 URL·이미지·깨진 링크(대상 파일 없음)는 **그대로 둡니다.**
+- 파일명이 트리 안에서 겹치면(`README.md` 여러 개 등) `[[wikilink]]` 로 바꾸지 않고 상대 링크를 유지합니다 — 이름만으로는 어느 노트인지 확정할 수 없기 때문입니다.
+- 코드블록·인라인 코드 안의 링크는 손대지 않습니다.
+
+### 보정 (`--fix`)
+
+변환기가 개선되기 전에 pull 한 문서에는 옛 결함의 흔적이 남아 있습니다. 스페이스를 통째로 다시 받지 않고 그 흔적만 되돌립니다.
+
+| 증상 | 보정 |
+| --- | --- |
+| frontmatter `title` 과 본문 `# 제목` 이 중복 | 겹치는 H1 제거 (Obsidian 에서 제목이 두 번 보임) |
+| 모든 코드블록이 ` ```java ` | 실제 Java 가 아니면 `plaintext` 로 (Confluence 가 언어 미지정 시 `brush: java` 를 붙이는 탓) |
+| 제목에 `[data-colorid=…]{color:#…}` | 본문에 새어 나온 CSS 제거 |
+| `:11\_eleven\_blue:` · `\[선택 가능\]` · `**7️⃣**\-**1️⃣**` | 불필요한 `\` 이스케이프 해제 |
+| 리스트 항목마다 빈 줄 | 같은 종류 항목끼리 붙임 (번호↔글머리 경계는 유지) |
+| 코드블록 안 줄 끝 공백 | 정리 |
+
+**멱등적입니다** — 두 번 돌려도 더 바뀌지 않고, 최신 pull 결과에는 아무것도 하지 않습니다. 애매하면 손대지 않는 쪽을 택하므로 진짜 Java 코드블록은 그대로 남습니다. 파일을 덮어쓰니 `--dry-run` 으로 먼저 확인하세요.
+
+반대로 **vault 를 그대로 push** 할 수 있습니다. Obsidian 문법을 그대로 이해합니다.
+
+| vault 에서 쓴 것 | Confluence 에 올라가는 것 |
+| --- | --- |
+| `[[설계]]` · `[[구조/설계\|설계 문서]]` | 페이지 링크 (짧은 이름·경로 모두 인식) |
+| `![[diagram.png]]` | 첨부 이미지 |
+| frontmatter `title:` | 페이지 제목 |
+| frontmatter `pageId:` | **그 페이지를 갱신** (새로 만들지 않음) |
+
+- 코드블록·인라인 코드 안의 `[[...]]` 는 건드리지 않고, **대상을 못 찾은 링크는 원문 그대로** 둡니다(조용히 사라지지 않습니다).
+- `.obsidian/` `.trash/` 등 숨김 폴더는 동기화 대상에서 제외됩니다.
+- `pageId` 덕분에 매핑 파일(`.confluence-sync.json`)을 잃어버려도 **중복 페이지가 생기지 않습니다** — 원본을 찾아가 갱신합니다(`[연결]` 로 표시).
+
+> pull → 편집 → push 왕복이 목적이라면 frontmatter 를 지우지 마세요. `pageId` 가 원본 페이지를 가리키는 유일한 단서입니다.
 
 ---
 
@@ -202,7 +305,7 @@ git push && git push --tags
 
 워크플로는 `package.json` 버전과 태그가 일치하는지 검증한 뒤 배포합니다. 변경 이력은 [CHANGELOG.md](CHANGELOG.md) 를 참고하세요.
 
-> 사전 설정: npm Automation 토큰을 저장소 **Settings → Secrets and variables → Actions** 에 `NPM_TOKEN` 으로 등록해야 합니다.
+> npm 발행은 **Trusted Publishing(OIDC)** 을 씁니다 — 장기 토큰 없이 GitHub Actions 가 단기 자격증명으로 배포합니다.
 
 ## 라이선스
 

package/dist/confluence.js

@@ -158,17 +158,22 @@ export function createClient(cfg, opts) {
         return res.json();
     }
     /**
-     * 콘텐츠 노드 조회. type + 제목 + export_view(HTML) + storage(원본 XHTML).
+     * 콘텐츠 노드 조회. type + 제목 + export_view(HTML) + storage(원본 XHTML) + 출처 메타.
      * storage 는 코드블록의 "진짜" 언어를 얻는 데 쓴다(export_view 는 언어 미지정 시 brush:java 기본값이 붙어 신뢰 불가).
+     * url/updated 는 frontmatter 의 출처 정보로 쓰이며, 응답에 없으면 undefined.
      */
     async function getNode(id) {
-        const data = await getV1(`/rest/api/content/${id}?expand=body.export_view,body.storage`);
+        const data = await getV1(`/rest/api/content/${id}?expand=body.export_view,body.storage,version`);
+        const base = data._links?.base;
+        const webui = data._links?.webui;
         return {
             id: data.id,
             type: data.type ?? 'page',
             title: data.title ?? id,
             html: data.body?.export_view?.value ?? '',
             storage: data.body?.storage?.value ?? '',
+            url: base && webui ? `${base}${webui}` : undefined,
+            updated: data.version?.when,
         };
     }
     /** 자식 노드 목록(kind = page|folder, 전체 페이지네이션). */

package/dist/convert.js

@@ -0,0 +1,242 @@
+/**
+ * `confluence-sync convert [--to obsidian|markdown] [--fix] [파일|폴더...] [--base <dir>] [--dry-run]`
+ * 이미 내려받은 .md 를 제자리에서 손본다. Confluence 호출도 인증도 없다.
+ *
+ *   --to obsidian  — 상대 .md 링크 → [[wikilink]]
+ *   --to markdown  — [[wikilink]] · ![[embed]] → 상대 .md 링크 (되돌리기)
+ *   --fix          — 옛 변환기가 남긴 흔적 보정(코드블록 언어·CSS 잔해·이스케이프·빈 줄)
+ *
+ * 스페이스를 통째로 다시 받지 않고도 최신 변환 품질을 얻기 위한 것이다.
+ * 링크는 대상이 트리 안에 실제로 있을 때만 바꾼다(외부 URL·이미지·깨진 링크는 손대지 않는다).
+ */
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
+import { resolve, relative, dirname, basename, join } from 'node:path';
+import { collectMarkdown, collectAssets, buildVault, vaultResolver } from './docs.js';
+import { linksToWikilinks, resolveWikilinks } from './obsidian.js';
+import { repairMarkdown, totalFixes } from './repair.js';
+import { bold, cyan, dim, gray, green, red, yellow } from './colors.js';
+function optVal(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
+const decode = (s) => { try {
+    return decodeURIComponent(s);
+}
+catch {
+    return s;
+} };
+const posix = (s) => s.split('\\').join('/');
+// ![alt](경로) — 본문이 참조하는 로컬 이미지(--out 으로 복사할 때 같이 옮긴다)
+const IMAGE = /!\[[^\]]*\]\((<[^>]+>|[^()\s]+)\)/g;
+/** md 본문이 참조하는 로컬 첨부의 절대경로들(외부 URL 제외, 실제 존재하는 것만). */
+function referencedAssets(text, fileAbs) {
+    const out = [];
+    for (const m of text.matchAll(IMAGE)) {
+        const dest = decode(m[1].replace(/^<(.*)>$/, '$1')).split('#')[0];
+        if (/^(https?:|data:)/i.test(dest))
+            continue;
+        const abs = resolve(dirname(fileAbs), dest);
+        if (existsSync(abs))
+            out.push(abs);
+    }
+    return out;
+}
+/** 준 경로들을 모두 담는 가장 가까운 폴더(파일은 그 파일이 있는 폴더로 친다). 인자가 없으면 null. */
+function commonAncestor(paths) {
+    if (!paths.length)
+        return null;
+    const dirs = paths.map((p) => {
+        const abs = resolve(p);
+        return statSync(abs).isDirectory() ? abs : dirname(abs);
+    });
+    const split = dirs.map((d) => d.split('/'));
+    const head = split[0];
+    let i = 0;
+    while (i < head.length && split.every((s) => s[i] === head[i]))
+        i++;
+    return split.length === 1 ? dirs[0] : head.slice(0, i).join('/') || '/';
+}
+/**
+ * 상대 .md 링크 → [[wikilink]].
+ * wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 트리 안에서 유일할 때만 바꾼다
+ * (겹치면 엉뚱한 노트로 이어질 수 있어 상대 링크를 그대로 둔다).
+ */
+function toObsidian(text, fileAbs, baseDir, nameCount) {
+    return linksToWikilinks(text, (dest, label) => {
+        if (/^(https?:|mailto:|#)/i.test(dest))
+            return null; // 외부 링크·앵커
+        const [pathPart, ...hash] = decode(dest).split('#');
+        if (!/\.md$/i.test(pathPart))
+            return null;
+        const targetAbs = resolve(dirname(fileAbs), pathPart);
+        if (!existsSync(targetAbs))
+            return null; // 깨진 링크는 손대지 않는다
+        if (relative(baseDir, targetAbs).startsWith('..'))
+            return null; // 트리 밖
+        const name = basename(targetAbs).replace(/\.md$/i, '');
+        if (nameCount.get(name) !== 1)
+            return null; // 이름이 겹치면 상대 링크 유지
+        const anchor = hash.length ? `#${hash.join('#')}` : '';
+        const l = label.trim();
+        return l && l !== name ? `[[${name}${anchor}|${l}]]` : `[[${name}${anchor}]]`;
+    });
+}
+export async function runConvert(argv) {
+    const toRaw = optVal(argv, '--to');
+    const fix = argv.includes('--fix');
+    if (toRaw !== undefined && toRaw !== 'obsidian' && toRaw !== 'markdown') {
+        console.error(red(`✗ 알 수 없는 변환 방향: ${toRaw}`) + '\n  --to obsidian | --to markdown');
+        process.exit(1);
+    }
+    const to = toRaw;
+    if (!to && !fix) {
+        console.error(red('✗ 할 일을 지정하세요: --to <형식> 또는 --fix') +
+            `\n  예) ${cyan('confluence-sync convert --to obsidian ./docs')}` +
+            `\n      ${cyan('confluence-sync convert --fix ./docs')}          ${dim('(옛 pull 결과 보정)')}` +
+            `\n      ${cyan('confluence-sync convert --to obsidian --fix ./docs')}  ${dim('(둘 다)')}`);
+        process.exit(1);
+    }
+    const dryRun = argv.includes('--dry-run');
+    // --out: 원본을 두고 변환 결과를 다른 트리에 쓴다(base 기준 상대 경로를 그대로 재현)
+    const outOpt = optVal(argv, '--out');
+    const outDir = outOpt ? resolve(outOpt) : undefined;
+    // 위치 인자: ['convert', <파일|폴더>...]  (옵션 값은 건너뛴다)
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--to' || argv[i] === '--base' || argv[i] === '--out') {
+            i++;
+            continue;
+        }
+        if (argv[i].startsWith('-'))
+            continue;
+        positionals.push(argv[i]);
+    }
+    const targets = positionals.slice(1); // [0] 은 'convert'
+    for (const t of targets) {
+        if (!existsSync(resolve(t))) {
+            console.error(red(`✗ 없는 경로: ${t}`));
+            process.exit(1);
+        }
+    }
+    /**
+     * baseDir 은 **링크를 해석하는 범위**다. 파일 하나만 고칠 때도 주변 문서를 알아야
+     * (이름이 유일한지·링크 대상이 실재하는지) 판정할 수 있다.
+     * 기본값은 준 경로들의 공통 상위 폴더 — 폴더를 주면 그 폴더, 파일을 주면 그 파일이 있는 폴더다.
+     * 링크 변환(--to)에서 트리 전체를 봐야 한다면 --base 로 루트를 지정한다.
+     */
+    const baseOpt = optVal(argv, '--base');
+    const baseDir = resolve(baseOpt ?? commonAncestor(targets) ?? process.cwd());
+    if (!existsSync(baseDir) || !statSync(baseDir).isDirectory()) {
+        console.error(red(`✗ --base 가 디렉토리가 아닙니다: ${baseDir}`));
+        process.exit(1);
+    }
+    const allMd = collectMarkdown(baseDir); // 링크 해석용(전체)
+    const mdRels = allMd.map((f) => posix(relative(baseDir, f)));
+    const vault = buildVault(mdRels, collectAssets(baseDir).map((f) => posix(relative(baseDir, f))));
+    // obsidian 방향의 이름 중복 검사도 트리 전체 기준이어야 한다
+    const nameCount = new Map();
+    for (const f of allMd) {
+        const n = basename(f).replace(/\.md$/i, '');
+        nameCount.set(n, (nameCount.get(n) ?? 0) + 1);
+    }
+    // 실제로 고쳐 쓸 파일(선택). 경로를 안 주면 base 전체.
+    const selected = targets.length
+        ? allMd.filter((f) => targets.some((t) => {
+            const abs = resolve(t);
+            return f === abs || f.startsWith(abs + '/');
+        }))
+        : allMd;
+    // base 밖의 .md 를 직접 지목한 경우(예: 이웃 폴더 파일) 는 위 필터에 안 걸린다
+    const outside = targets
+        .map((t) => resolve(t))
+        .filter((abs) => statSync(abs).isFile() && !allMd.includes(abs));
+    if (outside.length) {
+        console.error(yellow(`⚠ --base(${baseDir}) 밖의 파일은 건너뜁니다:`) + '\n  ' + outside.join('\n  '));
+    }
+    if (!selected.length) {
+        console.error(red('✗ 대상 .md 가 없습니다.') + dim('\n  (파일을 직접 지목했다면 --base 로 문서 트리 루트를 알려주세요)'));
+        process.exit(1);
+    }
+    const mdAbs = selected;
+    const jobs = [
+        to === 'obsidian' ? '상대 .md 링크 → [[wikilink]]' : to === 'markdown' ? '[[wikilink]] → 상대 .md 링크' : '',
+        fix ? '변환 흔적 보정' : '',
+    ].filter(Boolean).join(' + ');
+    const scope = mdAbs.length === allMd.length
+        ? `${mdAbs.length}건`
+        : `선택 ${mdAbs.length}/${allMd.length}건`;
+    if (outDir && (outDir === baseDir || outDir.startsWith(baseDir + '/'))) {
+        console.error(red(`✗ --out 이 base 안에 있습니다: ${outDir}`) + dim('\n  원본 트리를 덮어쓰지 않도록 base 밖의 경로를 쓰세요.'));
+        process.exit(1);
+    }
+    console.log(`${dim('base:')} ${cyan(baseDir)}\n` +
+        `${dim('대상:')} ${scope}  ${dim('—')}  ${jobs}` +
+        (outDir ? `\n${dim('출력:')} ${cyan(outDir)} ${dim('(원본 유지)')}` : '') +
+        (dryRun ? dim('  (dry-run)') : ''));
+    let changed = 0;
+    const copiedAssets = new Set();
+    const total = { cssJunk: 0, codeLang: 0, trailingWs: 0, escapes: 0, tightList: 0, dupTitle: 0 };
+    for (const abs of mdAbs) {
+        const rel = posix(relative(baseDir, abs));
+        const before = readFileSync(abs, 'utf8');
+        let text = before;
+        const notes = [];
+        // 보정을 먼저 한다 — 이스케이프가 풀려야(\[…\] → […]) 링크 인식이 정확해진다
+        if (fix) {
+            const r = repairMarkdown(text);
+            text = r.text;
+            const n = totalFixes(r.stats);
+            if (n) {
+                for (const k of Object.keys(total))
+                    total[k] += r.stats[k];
+                notes.push(dim(`보정 ${n}`));
+            }
+        }
+        if (to === 'obsidian')
+            text = toObsidian(text, abs, baseDir, nameCount);
+        else if (to === 'markdown')
+            text = resolveWikilinks(text, vaultResolver(rel, vault));
+        // 제자리 변환이면 바뀐 것만 쓰지만, --out 이면 대상 전부를 내보낸다(온전한 트리가 나와야 하므로)
+        if (!outDir && text === before)
+            continue;
+        if (outDir) {
+            const target = join(outDir, rel);
+            if (!dryRun) {
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, text);
+                // 이미지가 따라가지 않으면 링크가 깨진다 — 참조된 첨부를 같은 상대 위치로 복사
+                for (const asset of referencedAssets(text, abs)) {
+                    const arel = posix(relative(baseDir, asset));
+                    if (arel.startsWith('..') || copiedAssets.has(arel))
+                        continue; // base 밖 첨부는 두고 온다
+                    const dstAsset = join(outDir, arel);
+                    mkdirSync(dirname(dstAsset), { recursive: true });
+                    copyFileSync(asset, dstAsset);
+                    copiedAssets.add(arel);
+                }
+            }
+        }
+        else if (!dryRun) {
+            writeFileSync(abs, text);
+        }
+        // --out 이면 안 바뀐 파일도 그대로 내보내지만, 로그는 실제로 손댄 것만 남긴다
+        if (text !== before) {
+            changed++;
+            console.log(`  ${cyan('↻')}  ${rel}${notes.length ? '  ' + notes.join(' ') : ''}`);
+        }
+    }
+    console.log('\n' + bold('완료') + `  ${changed ? green(`${changed}개 파일 변경`) : gray('고칠 것 없음')}` +
+        (outDir ? `  ${cyan(`${mdAbs.length}개 파일 출력`)}${copiedAssets.size ? dim(`, 첨부 ${copiedAssets.size}`) : ''}` : '') +
+        `  ${dim(`대상 ${mdAbs.length}`)}`);
+    if (fix && totalFixes(total)) {
+        console.log(dim('  보정:') +
+            `  중복 제목 ${total.dupTitle}` +
+            `  코드블록 언어 ${total.codeLang}` +
+            `  CSS 잔해 ${total.cssJunk}` +
+            `  이스케이프 ${total.escapes}` +
+            `  리스트 빈 줄 ${total.tightList}` +
+            `  줄끝 공백 ${total.trailingWs}`);
+    }
+    if (dryRun)
+        console.log(dim('--dry-run: 파일을 쓰지 않았습니다.'));
+}

package/dist/docs.js

@@ -3,29 +3,90 @@
  * 폴더의 README.md 가 대표 페이지가 되고 같은 폴더의 다른 문서는 그 자식이 된다.
  */
 import { readdirSync, readFileSync } from 'node:fs';
-import { join, resolve, relative } from 'node:path';
+import { join, resolve, relative, basename, dirname } from 'node:path';
 import { splitTitleAndBody } from './markdown.js';
-/** dir 이하의 모든 .md 절대경로를 재귀 수집 */
-export function collectMarkdown(dir) {
+import { splitFrontmatter } from './obsidian.js';
+/**
+ * 숨김 디렉토리는 문서가 아니다. Obsidian vault 의 `.obsidian/`(설정)·`.trash/`(휴지통) 과
+ * `.git/`·`node_modules/` 가 여기서 걸러진다.
+ */
+const skipDir = (name) => name.startsWith('.') || name === 'node_modules';
+/** dir 이하의 파일 절대경로를 재귀 수집(pick 이 true 인 것만). */
+function walk(dir, pick) {
     const out = [];
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         const full = join(dir, entry.name);
-        if (entry.isDirectory())
-            out.push(...collectMarkdown(full));
-        else if (entry.isFile() && entry.name.endsWith('.md'))
+        if (entry.isDirectory()) {
+            if (!skipDir(entry.name))
+                out.push(...walk(full, pick));
+        }
+        else if (entry.isFile() && pick(entry.name)) {
             out.push(full);
+        }
     }
     return out;
 }
-/** base 상대 경로 → 문서 제목(첫 H1) 인덱스 */
+const isMd = (name) => name.toLowerCase().endsWith('.md');
+/** dir 이하의 모든 .md 절대경로를 재귀 수집 */
+export function collectMarkdown(dir) {
+    return walk(dir, isMd);
+}
+/** dir 이하의 .md 가 아닌 파일(이미지 등 첨부 후보) 절대경로를 재귀 수집 */
+export function collectAssets(dir) {
+    return walk(dir, (n) => !isMd(n));
+}
+/**
+ * 문서 1건을 읽어 제목·본문·frontmatter 로 분해한다.
+ * 제목 우선순위: frontmatter `title` > 첫 H1 > 파일명. H1 은 어느 경우든 본문에서 제거된다
+ * (Confluence 는 페이지 제목을 따로 가지므로 본문에 남으면 제목이 두 번 보인다).
+ */
+export function readDoc(baseDir, rel) {
+    const { data, body: afterFm } = splitFrontmatter(readFileSync(resolve(baseDir, rel), 'utf8'));
+    const { title, body } = splitTitleAndBody(afterFm, basename(rel).replace(/\.md$/i, ''));
+    return { title: (data.title || title).trim(), body, fm: data };
+}
+/** base 상대 경로 → 문서 제목 인덱스 */
 export function buildTitleIndex(rels, baseDir) {
     const idx = {};
-    for (const rel of rels) {
-        const { title } = splitTitleAndBody(readFileSync(resolve(baseDir, rel), 'utf8'), rel);
-        idx[rel] = title;
-    }
+    for (const rel of rels)
+        idx[rel] = readDoc(baseDir, rel).title;
     return idx;
 }
+/**
+ * wikilink 대상 이름 → base 상대 경로 인덱스.
+ * Obsidian 은 `[[파일명]]`(짧은 이름)과 `[[폴더/파일명]]`(경로) 을 모두 허용하므로 둘 다 등록한다.
+ * 짧은 이름이 겹치면 경로가 사전순으로 앞서는 쪽이 이긴다(Obsidian 의 "가장 가까운 것" 규칙과는 다르지만 결정적이다).
+ */
+export function buildVault(mdRels, assetRels) {
+    const index = (rels, stripExt) => {
+        const idx = {};
+        for (const rel of [...rels].sort()) {
+            const withoutExt = stripExt ? rel.replace(/\.md$/i, '') : rel;
+            for (const key of [withoutExt, basename(withoutExt)]) {
+                const k = key.toLowerCase();
+                if (!(k in idx))
+                    idx[k] = rel; // 먼저 등록된(사전순 앞선) 것이 이긴다
+            }
+        }
+        return idx;
+    };
+    return { notes: index(mdRels, true), assets: index(assetRels, false) };
+}
+/** 파일(rel) 기준으로 wikilink 대상을 상대경로로 풀어주는 resolver. */
+export function vaultResolver(rel, vault) {
+    const dir = dirname(rel) === '.' ? '' : dirname(rel);
+    return (target, embed) => {
+        const key = target.toLowerCase().replace(/\.md$/i, '');
+        // 임베드(![[...]])는 대개 이미지, 링크([[...]])는 대개 노트 → 각자 먼저 찾아본다
+        const hit = embed
+            ? (vault.assets[target.toLowerCase()] ?? vault.notes[key])
+            : (vault.notes[key] ?? vault.assets[target.toLowerCase()]);
+        if (!hit)
+            return null;
+        const r = relative(dir || '.', hit).split('\\').join('/');
+        return r || null;
+    };
+}
 const isReadme = (base) => /README\.md$/.test(base);
 /** 폴더 경로 → 그 폴더의 대표 README(base 상대) 인덱스 */
 export function buildFolderIndex(rels) {

package/dist/help.js

@@ -16,12 +16,14 @@ export function printHelp() {
     const h = (s) => bold(s); // 섹션 제목
     const o = (s) => cyan(s); // 옵션/명령
     console.log(`${bold(cyan(`confluence-sync v${readPkgVersion()}`))}
-${dim('Markdown 디렉토리를 Confluence Cloud 페이지로 단방향 동기화합니다.')}
+${dim('Confluence Cloud ↔ Markdown 양방향 동기화 CLI.')}
+${dim('짧은 이름')} ${o('csync')} ${dim('로도 실행할 수 있습니다(아래 confluence-sync 를 csync 로 대체 가능).')}
 
 ${h('사용법:')}
   ${o('confluence-sync')} [옵션] [경로...]      문서를 동기화(md → Confluence)
   ${o('confluence-sync init')}                  대화형으로 .env 설정 파일 생성
   ${o('confluence-sync pull <pageId|url>')}     Confluence 페이지/폴더를 .md 로 가져오기(역방향)
+  ${o('confluence-sync convert --to <형식>')}   이미 받은 .md 의 링크 표기를 바꾸기(로컬 전용)
   ${o('confluence-sync --help | --version')}
 
 ${h('동기화 옵션:')}
@@ -42,13 +44,37 @@ ${h('경로 인자:')}
   예)  ${o('confluence-sync 20-design')}        ${o('confluence-sync 90-glossary.md')}
 
 ${h('pull(역방향) 옵션:')}
-  ${o('--out <dir>')}       .md 를 생성할 디렉토리(기본: 현재 폴더)
-  ${o('--children')}        하위 페이지까지 재귀적으로 가져와 폴더 트리로 복원
-  ${o('--space')}          대상 없이 스페이스(CONFLUENCE_SPACE_KEY) 홈페이지부터 전체를 가져옴
+  ${o('--out <dir>')}         .md 를 생성할 디렉토리(기본: 현재 폴더)
+  ${o('--children')}          하위 페이지까지 재귀적으로 가져와 폴더 트리로 복원
+  ${o('--space')}             대상 없이 스페이스(CONFLUENCE_SPACE_KEY) 홈페이지부터 전체를 가져옴
+  ${o('--obsidian')}       내부 링크를 [[wikilink]] 로 출력(기본: 어디서나 열리는 상대 .md 링크)
   (이미지는 항상 attachments/<문서명>/ 하위에 저장됨)
   예)  ${o('confluence-sync pull https://.../pages/12345/Title --out ./docs --children')}
        ${o('confluence-sync pull --space --out ./docs')}
 
+${h('convert(이미 받아둔 .md 손보기) 옵션:')} ${dim('Confluence 호출·인증 없음')}
+  ${o('--to obsidian')}    상대 .md 링크 → [[wikilink]]
+  ${o('--to markdown')}    [[wikilink]] · ![[embed]] → 상대 .md 링크 (되돌리기)
+  ${o('--fix')}            옛 pull 결과 보정 — 코드블록 언어(java→plaintext)·CSS 잔해·
+                   불필요한 \\ 이스케이프·리스트 사이 빈 줄
+  ${o('--base <dir>')}     링크를 해석할 문서 트리 루트(기본: 준 경로들의 공통 상위 폴더)
+  ${o('--out <dir>')}      원본을 두고 결과를 다른 트리에 쓰기(참조된 첨부도 함께 복사)
+  ${o('--dry-run')}        바뀔 파일만 출력하고 쓰지 않음
+
+  파일·폴더를 여러 개 줄 수 있고, 안 주면 base 전체가 대상입니다.
+  ${o('--out')} 없이 실행하면 ${dim('원본 파일을 덮어씁니다')}.
+  예)  ${o('confluence-sync convert --fix ./docs --dry-run')}
+       ${o('confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault')}
+       ${o('confluence-sync convert --fix ./docs/가이드/설치.md --base ./docs')}  ${dim('(파일 하나만)')}
+
+${h('Obsidian:')}
+  pull 결과는 vault 에서 바로 열립니다. 함께 받은 페이지끼리의 내부 링크가 이어져 그래프·백링크가
+  동작하고, 각 문서의 frontmatter 에 pageId 가 남아 원본 페이지를 가리킵니다.
+  [[wikilink]] 표기를 원하면 ${o('pull --obsidian')}, 이미 받아둔 문서라면 ${o('convert --to obsidian')}.
+
+  push 는 vault 문법을 그대로 이해합니다: ${o('[[wikilink]]')} · ${o('![[embed]]')} · YAML frontmatter
+  (frontmatter 의 ${o('title')} 이 페이지 제목이 되고, ${o('pageId')} 가 있으면 매핑이 없어도 그 페이지를 갱신합니다).
+
 ${h('설정(.env):')}
   실행 위치(cwd)의 .env 또는 셸 환경변수를 읽습니다.
   필수: CONFLUENCE_BASE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_SPACE_KEY

package/dist/html2md.js

@@ -22,7 +22,7 @@ const linkDest = (p) => (/\s/.test(p) ? `<${p}>` : p);
  * (예: `**7️⃣**\-**1️⃣**` — 두 굵은 글씨 사이 텍스트 노드가 "-" 하나라 노드 시작으로 취급)
  * 줄 맨 앞의 진짜 마커 이스케이프는 보존하고, 그 뒤(줄 중간)의 것만 되돌린다. 코드블록은 건드리지 않는다.
  */
-function relaxEscapes(md) {
+export function relaxEscapes(md) {
     let inFence = false;
     return md
         .split('\n')
@@ -39,6 +39,8 @@ function relaxEscapes(md) {
             .slice(head.length)
             // 줄 중간의 - + . > 는 마커가 아니므로 이스케이프 불필요
             .replace(/\\([-+.>])/g, '$1')
+            // 단어 내부 밑줄은 CommonMark 에서 강조가 아니다 (:11_eleven_square_blue: 같은 이모지 코드)
+            .replace(/(\w)\\_(?=\w)/g, '$1_')
             // 링크가 아닌 대괄호 쌍(뒤에 ( 나 [ 가 오지 않음)은 이스케이프 불필요
             .replace(/\\\[([^[\]\n]*)\\\](?!\s*[([])/g, '[$1]');
         return head + rest;

package/dist/markdown.js

@@ -9,6 +9,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { resolve, relative, dirname, basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import MarkdownIt from 'markdown-it';
+import { resolveWikilinks } from './obsidian.js';
 export const escapeXml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 export const hashOf = (s) => createHash('sha256').update(s).digest('hex');
 /** markdown-it 이 퍼센트 인코딩한 링크/이미지 경로를 실제 경로로 디코드(실패 시 원본). */
@@ -83,11 +84,15 @@ export function splitTitleAndBody(markdown, fallback) {
     lines.splice(i, 1);
     return { title, body: lines.join('\n') };
 }
-/** 본문 markdown 을 storage format 으로 변환(base 기준 상대경로로 링크·이미지 해석). */
-export function toStorage(markdown, rel, titleIndex, base) {
+/**
+ * 본문 markdown 을 storage format 으로 변환(base 기준 상대경로로 링크·이미지 해석).
+ * resolveLink 를 주면 Obsidian 의 [[wikilink]]·![[embed]] 를 먼저 표준 링크로 정규화한다.
+ */
+export function toStorage(markdown, rel, titleIndex, base, resolveLink) {
     baseDir = base;
     ctx = { fileDir: dirname(rel) === '.' ? '' : dirname(rel), titleIndex, images: [], internalLinks: 0, linkStack: [], linkedTitles: new Set() };
-    const storage = md.render(markdown);
+    const src = resolveLink ? resolveWikilinks(markdown, resolveLink) : markdown;
+    const storage = md.render(src);
     return { storage, images: ctx.images, internalLinks: ctx.internalLinks, linkedTitles: [...ctx.linkedTitles] };
 }
 /**

package/dist/obsidian.js

@@ -0,0 +1,94 @@
+/**
+ * Obsidian 브릿지 — vault 관례와 이 도구의 표준 마크다운 사이를 잇는다.
+ *
+ * 원칙: **표준을 내보내고, 방언을 받아들인다.**
+ *  - push: vault 에서 쓴 YAML frontmatter · [[wikilink]] · ![[embed]] 를 이해해 그대로 발행한다.
+ *  - pull: Obsidian·GitHub·VS Code 어디서나 열리는 표준 상대 링크로 내보낸다
+ *          (frontmatter 의 pageId 가 왕복 동기화의 앵커가 된다).
+ *
+ * frontmatter 는 평면 `key: value` 만 다룬다. 중첩·리스트가 필요할 만큼 복잡한 메타데이터는
+ * 이 도구의 관심사가 아니며, 알 수 없는 키는 건드리지 않고 보존한다.
+ */
+const FENCE = /^\s*(?:```|~~~)/;
+// [[대상]] · [[대상|별칭]] · [[대상#헤딩]] · ![[임베드]]
+const WIKILINK = /(!?)\[\[([^\]|#]+)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
+/**
+ * 문서 맨 앞의 YAML frontmatter 를 분리한다. 없으면 data 는 빈 객체.
+ * `key: value` 한 줄짜리만 인식하고, 값의 감싼 따옴표는 벗긴다.
+ */
+export function splitFrontmatter(raw) {
+    const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+    if (!m)
+        return { data: {}, body: raw };
+    const data = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+        if (!kv)
+            continue; // 중첩/리스트 등 평면이 아닌 줄은 무시(보존은 하지 않음)
+        data[kv[1]] = kv[2].trim().replace(/^["'](.*)["']$/, '$1');
+    }
+    return { data, body: raw.slice(m[0].length) };
+}
+/** 평면 frontmatter 블록 생성. 값이 비면 그 키는 생략한다. */
+export function buildFrontmatter(data) {
+    const lines = Object.entries(data)
+        .filter(([, v]) => v !== undefined && v !== null && v !== '')
+        // 콜론·따옴표·선행 특수문자가 있으면 YAML 이 깨지므로 인용한다
+        .map(([k, v]) => `${k}: ${/[:#"'\n]|^\s|\s$/.test(v) ? JSON.stringify(v) : v}`);
+    return lines.length ? `---\n${lines.join('\n')}\n---\n\n` : '';
+}
+/** 공백이 있으면 <...> 로 감싼다(markdown-it 이 목적지를 통째로 파싱하도록). */
+const dest = (p) => (/\s/.test(p) ? `<${p}>` : p);
+/**
+ * 마크다운 본문에서 "산문" 부분에만 변환을 적용한다.
+ * 코드블록(``` / ~~~)과 인라인 코드(`...`) 안은 그대로 둔다 — 링크처럼 생긴 예제 코드를
+ * 망가뜨리지 않기 위해서다.
+ */
+function mapProse(md, fn) {
+    let inFence = false;
+    return md
+        .split('\n')
+        .map((line) => {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            return line;
+        }
+        if (inFence)
+            return line;
+        // 홀수 인덱스 = 인라인 코드 스팬 → 원문 유지
+        return line
+            .split(/(`+[^`]*`+)/)
+            .map((seg, i) => (i % 2 ? seg : fn(seg)))
+            .join('');
+    })
+        .join('\n');
+}
+/**
+ * [[wikilink]] · ![[embed]] → 표준 마크다운 링크.
+ * 해석에 실패한 링크는 원문 그대로 남겨 (조용히 사라지지 않고) 눈에 띄게 한다.
+ */
+export function resolveWikilinks(md, resolve) {
+    return mapProse(md, (s) => s.replace(WIKILINK, (whole, bang, target, hash, alias) => {
+        const embed = bang === '!';
+        const found = resolve(target.trim(), embed);
+        if (!found)
+            return whole; // 해석 실패 → 원문 보존
+        const label = (alias ?? target).trim();
+        return embed ? `![${label}](${dest(found)})` : `[${label}](${dest(found + (hash ?? ''))})`;
+    }));
+}
+// [text](dest) — dest 는 <...> 로 감싸였을 수 있다. 앞의 ! 는 이미지 임베드.
+const MD_LINK = /(!?)\[([^\]]*)\]\((<[^>]+>|[^()\s]+)\)/g;
+/**
+ * 표준 마크다운 링크 → [[wikilink]] (resolveWikilinks 의 역변환).
+ * toWikilink 가 null 을 주면(= 외부 URL·이미지·대상 불명) 그 링크는 그대로 둔다.
+ * 이미지 임베드(`![...]()`)는 건드리지 않는다 — 표준 문법이 Obsidian 에서도 그대로 렌더된다.
+ */
+export function linksToWikilinks(md, toWikilink) {
+    return mapProse(md, (s) => s.replace(MD_LINK, (whole, bang, label, rawDest) => {
+        if (bang === '!')
+            return whole; // 이미지는 표준 링크 유지
+        const d = rawDest.replace(/^<(.*)>$/, '$1');
+        return toWikilink(d, label) ?? whole;
+    }));
+}

package/dist/pull.js

@@ -2,16 +2,22 @@
  * `confluence-sync pull <pageId|url> [--out <dir>] [--children]`
  * Confluence 페이지를 읽어 Markdown(.md) 으로 생성한다(역방향).
  * 자식이 있는 페이지는 push 관례를 역으로 적용해 <slug>/README.md 폴더로 펼친다.
- * 첨부는 .md 옆에 내려받고 이미지 링크를 로컬 파일명으로 재작성한다.
+ * 첨부는 attachments/<문서명>/ 하위에 내려받고 이미지 링크를 그 경로로 재작성한다.
+ *
+ * 함께 받은 페이지끼리의 내부 링크는 마지막에 상대 .md 경로로 이어 붙인다(Obsidian 그래프·백링크가 살아난다).
+ * 각 문서 머리에 pageId 를 담은 frontmatter 를 남겨, 매핑 파일 없이도 push 가 원본 페이지를 다시 찾아간다.
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { resolve, join, dirname, basename } from 'node:path';
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { resolve, join, dirname, basename, relative } from 'node:path';
 import { readEnv, requireEnv } from './config.js';
 import { createClient } from './confluence.js';
 import { htmlToMarkdown, codeLanguagesFromStorage } from './html2md.js';
+import { buildFrontmatter } from './obsidian.js';
 import { cyan, dim, green, red, yellow } from './colors.js';
 // 첨부 이미지는 항상 <md위치>/attachments/<문서명>/ 하위에 저장한다.
 const ASSETS_DIR = 'attachments';
+/** 마크다운 링크 중 Confluence 페이지를 가리키는 것: [text](https://.../pages/<id>/...) */
+const PAGE_LINK = /\[([^\]]*)\]\(<?(https?:\/\/[^\s)<>]*?\/pages\/(\d+)[^\s)<>]*?)>?\)/g;
 function optVal(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
@@ -28,8 +34,11 @@ function parseContentId(input) {
 function slug(title) {
     return title.replace(/[\/\\:*?"<>|]/g, '-').replace(/\s+/g, ' ').trim() || 'untitled';
 }
+/** 공백이 있으면 <...> 로 감싼 마크다운 링크 목적지 */
+const dest = (p) => (/\s/.test(p) ? `<${p}>` : p);
 /** 페이지 1건을 .md 로 생성(자식 페이지/폴더가 있으면 <slug>/README.md 폴더로). */
-async function pullPage(client, node, destDir, withChildren) {
+async function pullPage(ctx, node, destDir) {
+    const { client, withChildren } = ctx;
     const { id, title, html, storage } = node;
     // 페이지도 하위 페이지 + 하위 폴더를 모두 가질 수 있다(폴더가 페이지 밑에 올 수 있음).
     const childFolders = withChildren ? await client.getChildFolders(id) : [];
@@ -66,19 +75,33 @@ async function pullPage(client, node, destDir, withChildren) {
             }
         }
     }
-    writeFileSync(filePath, `# ${title}\n\n${body}`);
+    // frontmatter 의 pageId 는 push 왕복의 앵커다(매핑 파일이 없어도 원본 페이지를 찾아간다).
+    // 취향 옵션이 아니라 중복 페이지 생성을 막는 장치이므로 항상 쓴다. Obsidian 은 이를 속성으로 보여준다.
+    const fm = buildFrontmatter({
+        title,
+        pageId: id,
+        spaceKey: ctx.spaceKey,
+        source: node.url ?? '',
+        updated: node.updated ?? '',
+    });
+    // 제목은 frontmatter 의 title 하나로 충분하다. 본문에 `# 제목` 을 또 넣으면
+    // 제목을 따로 표시하는 뷰어(Obsidian 등)에서 두 번 보인다. push 도 title 속성을 먼저 읽는다.
+    writeFileSync(filePath, fm ? `${fm}${body}` : `# ${title}\n\n${body}`);
+    ctx.written.push(filePath);
+    ctx.pathById.set(id, filePath);
     const imgNote = referenced.size ? `, 이미지 ${referenced.size}` : '';
     console.log(`  ${green('＋ 생성')}  ${filePath}  ${dim(`(#${id}${imgNote})`)}`);
     const counts = { pages: 1, folders: 0 };
     for (const f of childFolders)
-        add(counts, await pullNode(client, f.id, folder, withChildren));
+        add(counts, await pullNode(ctx, f.id, folder));
     for (const c of childPages)
-        add(counts, await pullNode(client, c.id, folder, withChildren));
+        add(counts, await pullNode(ctx, c.id, folder));
     return counts;
 }
 function add(acc, c) { acc.pages += c.pages; acc.folders += c.folders; }
 /** 노드(페이지/폴더)를 재귀적으로 가져온다. 폴더는 디렉토리(본문 없음)로 만든다. 노드 하나 실패는 스킵. */
-async function pullNode(client, id, destDir, withChildren) {
+async function pullNode(ctx, id, destDir) {
+    const { client, withChildren } = ctx;
     try {
         const node = await client.getNode(id);
         if (node.type === 'folder') {
@@ -88,9 +111,9 @@ async function pullNode(client, id, destDir, withChildren) {
             const counts = { pages: 0, folders: 1 };
             if (withChildren) {
                 for (const f of await client.getChildFolders(id))
-                    add(counts, await pullNode(client, f.id, dir, true));
+                    add(counts, await pullNode(ctx, f.id, dir));
                 for (const p of await client.getChildPages(id))
-                    add(counts, await pullNode(client, p.id, dir, true));
+                    add(counts, await pullNode(ctx, p.id, dir));
             }
             else {
                 console.log(dim('     (하위 내용은 --children 으로 가져옵니다)'));
@@ -98,13 +121,46 @@ async function pullNode(client, id, destDir, withChildren) {
             return counts;
         }
         // page: getNode 결과(html + storage) 그대로 사용
-        return await pullPage(client, node, destDir, withChildren);
+        return await pullPage(ctx, node, destDir);
     }
     catch (e) {
         console.error(red(`  ✗ 실패  #${id}`) + `\n${e.message}`);
         return { pages: 0, folders: 0 };
     }
 }
+/**
+ * 함께 받은 페이지를 가리키는 절대 Confluence URL 을 상대 .md 링크(또는 [[wikilink]])로 바꾼다.
+ * 이번에 받지 않은 페이지의 링크는 절대 URL 그대로 둔다(깨진 링크를 만들지 않는다).
+ * 반환값은 재작성한 링크 수.
+ */
+export function relinkPass(written, pathById, wikilinks) {
+    const noExt = (p) => basename(p).replace(/\.md$/i, '');
+    // wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 유일할 때만 안전하게 쓸 수 있다.
+    const nameCount = new Map();
+    for (const p of pathById.values())
+        nameCount.set(noExt(p), (nameCount.get(noExt(p)) ?? 0) + 1);
+    let count = 0;
+    for (const file of written) {
+        const before = readFileSync(file, 'utf8');
+        const after = before.replace(PAGE_LINK, (whole, text, url, id) => {
+            const target = pathById.get(id);
+            if (!target || target === file)
+                return whole; // 못 받은 페이지·자기 자신 → 원본 URL 유지
+            count++;
+            const name = noExt(target);
+            const label = (text || name).trim();
+            if (wikilinks && nameCount.get(name) === 1) {
+                return label === name ? `[[${name}]]` : `[[${name}|${label}]]`;
+            }
+            const anchor = url.includes('#') ? '#' + url.split('#').slice(1).join('#') : '';
+            const rel = relative(dirname(file), target).split('\\').join('/');
+            return `[${label}](${dest(rel + anchor)})`;
+        });
+        if (after !== before)
+            writeFileSync(file, after);
+    }
+    return count;
+}
 export async function runPull(argv) {
     const withChildren = argv.includes('--children');
     const wholeSpace = argv.includes('--space');
@@ -112,6 +168,19 @@ export async function runPull(argv) {
     const env = readEnv();
     requireEnv(env);
     const client = createClient({ baseUrl: env.baseUrl, email: env.email, token: env.token }, { force: false, verify: false });
+    const ctx = {
+        client,
+        withChildren,
+        obsidian: argv.includes('--obsidian'),
+        spaceKey: env.spaceKey,
+        written: [],
+        pathById: new Map(),
+    };
+    const done = (c) => {
+        const relinked = relinkPass(ctx.written, ctx.pathById, ctx.obsidian);
+        console.log(`\n${green('완료')}  페이지 ${c.pages}개${c.folders ? `, 폴더 ${c.folders}개` : ''} 생성` +
+            (relinked ? `  ${cyan(`내부링크 ${relinked}개 연결`)}` : ''));
+    };
     // --space: 스페이스 홈페이지(콘텐츠 트리 루트)부터 전체를 재귀적으로 가져옴
     if (wholeSpace) {
         const { homepageId } = await client.getSpaceInfo(env.spaceKey);
@@ -120,8 +189,8 @@ export async function runPull(argv) {
             process.exit(1);
         }
         console.log(`${dim('pull:')} space ${cyan(env.spaceKey)} ${dim('→')} ${cyan(outDir)} ${dim('(전체)')}`);
-        const { pages, folders } = await pullNode(client, homepageId, outDir, true);
-        console.log(`\n${green('완료')}  페이지 ${pages}개${folders ? `, 폴더 ${folders}개` : ''} 생성`);
+        ctx.withChildren = true;
+        done(await pullNode(ctx, homepageId, outDir));
         return;
     }
     // 위치 인자: ['pull', <pageId|url>, ...]
@@ -146,6 +215,5 @@ export async function runPull(argv) {
         process.exit(1);
     }
     console.log(`${dim('pull:')} #${contentId} ${dim('→')} ${cyan(outDir)}${withChildren ? dim(' (+children)') : ''}`);
-    const { pages, folders } = await pullNode(client, contentId, outDir, withChildren);
-    console.log(`\n${green('완료')}  페이지 ${pages}개${folders ? `, 폴더 ${folders}개` : ''} 생성`);
+    done(await pullNode(ctx, contentId, outDir));
 }

package/dist/repair.js

@@ -0,0 +1,145 @@
+/**
+ * 이미 내려받아 둔 .md 를 고친다(사후 보정).
+ *
+ * html2md 가 개선되기 전에 pull 한 문서에는 변환기 결함의 흔적이 남아 있다.
+ * 스페이스를 통째로 다시 받지 않고도 같은 결과를 얻도록, 그 흔적들만 골라 되돌린다.
+ * 파일을 덮어쓰므로 **확실한 것만** 고치고, 애매하면 손대지 않는다.
+ */
+import { relaxEscapes } from './html2md.js';
+import { splitFrontmatter } from './obsidian.js';
+const emptyStats = () => ({ cssJunk: 0, codeLang: 0, trailingWs: 0, escapes: 0, tightList: 0, dupTitle: 0 });
+export const totalFixes = (s) => Object.values(s).reduce((a, b) => a + b, 0);
+const FENCE = /^\s*(?:```|~~~)/;
+/** 리스트 항목이면 종류('ul'|'ol'), 아니면 null. 종류가 다르면 별개의 리스트다. */
+function listKind(line) {
+    if (/^[ \t]*[-*+]\s/.test(line))
+        return 'ul';
+    if (/^[ \t]*\d+[.)]\s/.test(line))
+        return 'ol';
+    return null;
+}
+/**
+ * Confluence export_view 는 색상 텍스트용 인라인 <style> 을 본문에(제목 안까지) 끼워 넣는데,
+ * 예전 변환기는 그 CSS 텍스트를 그대로 뱉었다. `[data-colorid=xxx]{color:#fff;}` 같은 잔해다.
+ * (turndown 이 이스케이프해 `\[data-colorid=...\]` 형태로 남아 있기도 하다.)
+ */
+function stripCssJunk(line) {
+    return line
+        .replace(/\\?\[data-colorid=[^\]]*\\?\]\s*\{[^}]*\}/g, '') // 선택자 + 규칙 블록
+        .replace(/\\?\[data-colorid=[^\]]*\\?\]/g, '') // 선택자만 남은 것
+        .replace(/\{\s*color\s*:\s*[^}]*\}/g, ''); // 규칙만 남은 것
+}
+/**
+ * 실제 Java 코드로 보이는가?
+ * Confluence 는 언어를 지정하지 않은 code 매크로를 export 할 때 `brush: java` 를 기본으로 붙인다.
+ * 그래서 예전 변환기는 거의 모든 코드블록을 ```java 로 찍었다. 진짜 Java 만 남기고 plaintext 로 되돌린다.
+ */
+function looksLikeJava(code) {
+    return (/^\s*(package|import)\s+(java|javax|com|org)\b/m.test(code) ||
+        /\b(public|private|protected)\s+(static\s+)?(final\s+)?(class|interface|enum|void)\b/.test(code) ||
+        /\bSystem\.(out|err)\.print/.test(code) ||
+        /@Override\b/.test(code));
+}
+/**
+ * 리스트 항목 사이의 빈 줄을 없앤다(Confluence 의 <li><p> 때문에 생긴 loose list).
+ * 앞뒤가 **같은 종류**의 항목일 때만 붙인다 — 번호 목록과 글머리 목록이 잇달아 나오는 경우
+ * 그 사이의 빈 줄은 두 리스트를 갈라놓는 구분자라 지우면 하나로 합쳐져 버린다.
+ */
+function tightenLists(lines, stats) {
+    const out = [];
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (FENCE.test(line))
+            inFence = !inFence;
+        if (!inFence && line.trim() === '' && out.length) {
+            const prev = listKind(out[out.length - 1]);
+            const next = listKind(lines[i + 1] ?? '');
+            if (prev && prev === next) {
+                stats.tightList++;
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * frontmatter 에 title 이 있는데 본문 첫 헤딩이 같은 제목이면 그 H1 을 지운다.
+ * 제목을 따로 표시하는 뷰어(Obsidian 등)에서 제목이 두 번 보이기 때문이다.
+ * 제목이 다르면(본문이 실제로 다른 이야기로 시작하면) 손대지 않는다.
+ */
+function dropDuplicateTitle(src, stats) {
+    const { data, body } = splitFrontmatter(src);
+    if (!data.title)
+        return src;
+    const lines = body.split('\n');
+    const i = lines.findIndex((l) => l.trim() !== '');
+    if (i === -1)
+        return src;
+    const h1 = lines[i].match(/^#\s+(.*)$/);
+    if (!h1 || h1[1].trim() !== data.title.trim())
+        return src;
+    lines.splice(i, 1);
+    while (lines[i]?.trim() === '')
+        lines.splice(i, 1); // H1 뒤에 붙어 있던 빈 줄까지
+    stats.dupTitle++;
+    const fmBlock = src.slice(0, src.length - body.length);
+    return fmBlock + lines.join('\n');
+}
+/** 문서 하나를 보정한다. 반환된 text 가 원본과 같으면 고칠 것이 없었다는 뜻. */
+export function repairMarkdown(input) {
+    const stats = emptyStats();
+    const src = dropDuplicateTitle(input, stats);
+    const lines = src.split('\n');
+    const out = [];
+    let inFence = false;
+    let fenceStart = -1; // out 기준, 현재 코드블록 여는 줄의 인덱스
+    for (const raw of lines) {
+        if (FENCE.test(raw)) {
+            if (!inFence) {
+                inFence = true;
+                fenceStart = out.length;
+                out.push(raw);
+            }
+            else {
+                // 코드블록 종료 — 모아둔 내용으로 언어를 판정한다
+                inFence = false;
+                const opener = out[fenceStart];
+                if (/^\s*(?:```|~~~)java\s*$/.test(opener)) {
+                    const code = out.slice(fenceStart + 1).join('\n');
+                    if (!looksLikeJava(code)) {
+                        out[fenceStart] = opener.replace(/java\s*$/, 'plaintext');
+                        stats.codeLang++;
+                    }
+                }
+                out.push(raw);
+            }
+            continue;
+        }
+        if (inFence) {
+            // 코드 안에서는 줄 끝 공백만 정리한다(코드 의미는 불변). 이스케이프·CSS 는 손대지 않는다.
+            const trimmed = raw.replace(/[ \t]+$/, '');
+            if (trimmed !== raw)
+                stats.trailingWs++;
+            out.push(trimmed);
+            continue;
+        }
+        let line = raw;
+        const noCss = stripCssJunk(raw);
+        if (noCss !== raw) {
+            stats.cssJunk++;
+            // 잔해를 걷어낸 자리에 공백이 남는다: "#  {제거됨} 제목" → "# 제목"
+            line = noCss.replace(/[ \t]{2,}/g, ' ').replace(/[ \t]+$/, '');
+        }
+        out.push(line);
+    }
+    // 이스케이프 완화는 코드블록을 알아서 건너뛴다(html2md 와 같은 규칙을 재사용)
+    let text = relaxEscapes(tightenLists(out, stats).join('\n'));
+    // relaxEscapes 가 어디를 바꿨는지 역추적하긴 어려우니, 사라진 백슬래시 개수로 센다
+    const backslashes = (s) => (s.match(/\\/g) || []).length;
+    stats.escapes = Math.max(0, backslashes(src) - backslashes(text));
+    // CSS 잔해를 걷어내면 빈 껍데기 제목(`#` 만 남은 줄)이 생길 수 있다
+    text = text.replace(/^#{1,6}[ \t]*$/gm, '');
+    return { text, stats };
+}

package/dist/sync.js

@@ -14,15 +14,16 @@
  * 세부 로직은 ./markdown ./docs ./mapping ./confluence ./config ./init ./help 모듈에 있다.
  */
 import 'dotenv/config';
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import { readEnv, requireEnv } from './config.js';
-import { toStorage, splitTitleAndBody, docHash } from './markdown.js';
-import { collectMarkdown, buildTitleIndex, buildFolderIndex, parentKeyOf, containerKeyOf, sortForSync, resolveSelection, withParents, } from './docs.js';
+import { toStorage, docHash } from './markdown.js';
+import { collectMarkdown, collectAssets, buildTitleIndex, buildFolderIndex, buildVault, vaultResolver, readDoc, parentKeyOf, containerKeyOf, sortForSync, resolveSelection, withParents, } from './docs.js';
 import { loadMapping, saveMapping } from './mapping.js';
 import { createClient } from './confluence.js';
 import { runInit } from './init.js';
 import { runPull } from './pull.js';
+import { runConvert } from './convert.js';
 import { buildIgnorer } from './ignore.js';
 import { printHelp, readPkgVersion } from './help.js';
 import { bold, dim, red, green, yellow, magenta, cyan, gray } from './colors.js';
@@ -51,7 +52,8 @@ const EXCLUDES = optVals('--exclude');
 // 위치 인자(선택 경로/서브커맨드): 플래그·옵션값 제외
 const positionals = [];
 for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--base' || argv[i] === '--mapping' || argv[i] === '--exclude') {
+    if (argv[i] === '--base' || argv[i] === '--mapping' || argv[i] === '--exclude'
+        || argv[i] === '--to' || argv[i] === '--out') {
         i++;
         continue;
     }
@@ -76,6 +78,10 @@ if (positionals[0] === 'pull') {
     await runPull(argv);
     process.exit(0);
 }
+if (positionals[0] === 'convert') {
+    await runConvert(argv);
+    process.exit(0);
+}
 const baseInput = optVal('--base') ?? process.env.CONFLUENCE_SYNC_BASE;
 if (!baseInput) {
     console.error(red('✗ 동기화 루트가 지정되지 않았습니다.') + '\n' +
@@ -103,6 +109,9 @@ async function main() {
     const ignoredCount = collected.length - allRel.length;
     const folderIndex = buildFolderIndex(allRel);
     const titleIndex = buildTitleIndex(allRel, BASE_DIR); // 링크 변환은 항상 전체 기준
+    // Obsidian [[wikilink]] 해석용 이름 인덱스. 제외된 문서는 링크 대상에서도 빠진다.
+    const vault = buildVault(allRel, collectAssets(BASE_DIR).map((f) => relative(BASE_DIR, f)));
+    const render = (rel, body) => toStorage(body, rel, titleIndex, BASE_DIR, vaultResolver(rel, vault));
     const selected = positionals.length
         ? withParents(resolveSelection(allRel, positionals, BASE_DIR), folderIndex)
         : allRel;
@@ -148,11 +157,14 @@ async function main() {
                     const fex = mapping[`${d}/`];
                     console.log(`  [${fex?.pageId ? gray('폴더') : green('폴더+')}] 📁 ${d}/`);
                 }
-            const { title, body } = splitTitleAndBody(readFileSync(resolve(BASE_DIR, rel), 'utf8'), rel);
-            const r = toStorage(body, rel, titleIndex, BASE_DIR);
+            const { title, body, fm } = readDoc(BASE_DIR, rel);
+            const r = render(rel, body);
             const hash = docHash(title, r);
             const ex = mapping[rel];
-            const status = !ex?.pageId ? green('신규') : ex.hash === hash ? gray('동일') : yellow('변경');
+            // 매핑엔 없지만 frontmatter 에 pageId 가 있으면 신규 생성이 아니라 기존 페이지에 연결된다
+            const status = !ex?.pageId
+                ? (fm.pageId ? cyan('연결') : green('신규'))
+                : ex.hash === hash ? gray('동일') : yellow('변경');
             const pk = parentKeyOf(rel, folderIndex);
             console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}, 이미지: ${r.images.length})`)}`);
         }
@@ -166,7 +178,7 @@ async function main() {
         saveMapping(MAPPING_PATH, {});
     }
     const work = REBUILD ? {} : mapping;
-    let created = 0, updated = 0, skipped = 0, recreated = 0, relinked = 0, foldersMade = 0;
+    let created = 0, updated = 0, skipped = 0, recreated = 0, relinked = 0, foldersMade = 0, linked = 0;
     const rendered = new Map();
     const recreatedTitles = new Set(); // 이번에 재생성된 문서의 제목
     const touched = new Set(); // 이번에 발행(생성/갱신/재생성)된 문서
@@ -216,8 +228,8 @@ async function main() {
             console.error(yellow(`  ✗ 건너뜀  ${rel}  (상위 폴더 미생성)`));
             continue;
         }
-        const { title, body } = splitTitleAndBody(readFileSync(resolve(BASE_DIR, rel), 'utf8'), rel);
-        const r = toStorage(body, rel, titleIndex, BASE_DIR);
+        const { title, body, fm } = readDoc(BASE_DIR, rel);
+        const r = render(rel, body);
         const hash = docHash(title, r);
         const pk = parentKeyOf(rel, folderIndex);
         const parentId = pk ? work[pk]?.pageId : env.parentId;
@@ -226,6 +238,24 @@ async function main() {
             console.error(yellow(`  ✗ 건너뜀  ${rel}  (부모 '${pk}' 가 아직 없음)`));
             continue;
         }
+        // pull 로 받은 문서(frontmatter 에 pageId)는 매핑이 없어도 원본 페이지에 다시 연결한다.
+        // 매핑 파일을 잃었거나 vault 를 다른 곳에 복제한 경우 중복 생성을 막아준다.
+        if (!work[rel]?.pageId && fm.pageId) {
+            try {
+                if (await client.getContentOrNull(fm.pageId)) {
+                    work[rel] = { pageId: fm.pageId, title };
+                    saveMapping(MAPPING_PATH, work);
+                    console.log(`  ${cyan('🔗 연결')}  ${rel}  ${dim(`→ 기존 페이지 #${fm.pageId}`)}`);
+                    linked++;
+                }
+                else {
+                    console.error(yellow(`  ⚠ frontmatter 의 pageId #${fm.pageId} 를 찾을 수 없습니다 → 새로 생성  (${rel})`));
+                }
+            }
+            catch (e) {
+                console.error(yellow(`  ⚠ pageId 확인 실패 #${fm.pageId}: ${e.message}`));
+            }
+        }
         try {
             const result = await client.upsertPage(work, spaceId, rel, title, r.storage, hash, parentId);
             saveMapping(MAPPING_PATH, work);
@@ -282,6 +312,7 @@ async function main() {
         `  ${magenta(`재생성 ${recreated}`)}` +
         `  ${cyan(`링크재연결 ${relinked}`)}` +
         `  ${gray(`변경없음 ${skipped}`)}` +
+        (linked ? `  ${cyan(`연결 ${linked}`)}` : '') +
         (foldersMade ? `  ${cyan(`폴더 ${foldersMade}`)}` : '') +
         `  ${dim(`대상 ${files.length}`)}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonseok-han/confluence-sync",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Confluence Cloud ↔ Markdown 양방향 동기화 CLI — 마크다운을 Confluence 페이지로 발행(push)하고, Confluence 페이지·폴더·스페이스를 마크다운으로 가져옵니다(pull).",
   "keywords": [
@@ -26,7 +26,8 @@
     "node": ">=20"
   },
   "bin": {
-    "confluence-sync": "dist/sync.js"
+    "confluence-sync": "dist/sync.js",
+    "csync": "dist/sync.js"
   },
   "files": [
     "dist",